<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html><head>
<meta http-equiv="Content-Language" content="en-us">

<title>Add-ons</title><link rel="stylesheet" type="text/css" href="../style.css"></head>


<body>

<div align="center">
<table class="allEncompassingTable">
 <tbody><tr>
  <td>
<p><a href="../index.html" target="_top"><img src="images/homeImg.png"></a></p>



<h1>Add-ons</h1>

<p>An add-on in CoppeliaSim is quite similar to a <a href="plugins.htm">plugin</a>:
it is automatically loaded at program start-up, and allows CoppeliaSim's
functionality to be extended by user-written functionality or
functions. Add-ons  are written in <a href="http://www.lua.org">Lua</a>. Two types of add-ons are supported:</p>

<li><a name="function"></a><strong>Add-on functions</strong>: add-on&nbsp;functions appear
first in the add-on menu. They can be seen as functions that will be
executed once, when selected by the user. Importers and exporters can
conveniently be implemented with them. </li>
<li><a name="script"></a><strong>Add-on scripts</strong>: add-on scripts are persistent across all opened scenes, and are executed
constantly, effectively running in the
background. They should only execute minimalistic code everytime they
are called, since the whole application would otherwise slow down.
Add-on scripts are called frequently by the system, with a <a href="scriptExecution.htm">precise order</a>. Add-on scripts share a lot of properties with <a href="sandboxScript.htm">the sandbox script</a>.</li>

<p>Add-on functions and scripts should be written in a text file located in the
same folder as the main application, with following naming convention:</p>

<li><strong>simAddOnFunc_xxxx.lua</strong>, where xxxx can be any string representing the name of an add-on function.</li>
<li><strong>simAddOnScript_xxxx.lua</strong>, where xxxx can be any
string representing the name of the add-on script. The add-on script
will be automatically started. Selecting it in the add-on menu allows
pausing/unpausing its execution. The script can request termination by returning sim.syscb_cleanup.</li>
<li><strong>simAddOnScript-xxxx.lua</strong>, where xxxx can be any
string representing the name of the add-on script. The add-on script
will not be automatically started. The user can start/pause/unpause it when required
by selecting it in the add-on menu. The script can request termination by returning sim.syscb_cleanup.</li>

<p>Add-on scripts that do not follow above naming convention can still be loaded and run via <a href="commandLine.htm">command line options</a>.</p>

<p>An add-on script should be segmented into several system callback functions, as following skeleton script illustrates: </p>


<pre class=lightRedBox>
-- Return sim.syscb_cleanup if you wish to stop the add-on script

function <strong>sysCall_init</strong>() -- not optional!
    -- do some initialization here
end

function <strong>sysCall_cleanup</strong>()
    -- do some clean-up here
end

function <strong>sysCall_nonSimulation</strong>()
    -- is executed when simulation is not running
end

function <strong>sysCall_beforeSimulation</strong>()
    -- Simulation is about to start
end

function <strong>sysCall_beforeMainScript</strong>()
    -- Can be used to step a simulation in a custom manner.
    local outData={doNotRunMainScript=false} -- when true, then the main script won't be executed
    return outData
end

function <strong>sysCall_actuation</strong>()
    -- put some actuation code here.
end

function <strong>sysCall_sensing</strong>()
    -- put some sensing code here.
end

function <strong>sysCall_afterSimulation</strong>()
    -- Simulation has just ended
end

function <strong>sysCall_suspend</strong>()
    -- Simulation is about to be suspended
end

function <strong>sysCall_suspended</strong>()
    -- Simulation is suspended
end

function <strong>sysCall_resume</strong>()
    -- Simulation is about to resume
end

function <strong>sysCall_addOnScriptSuspend</strong>()
    -- Add-on script is about to be suspended
end

function <strong>sysCall_addOnScriptSuspended</strong>()
    -- Add-on script is suspended
end

function <strong>sysCall_addOnScriptResume</strong>()
    -- Add-on script is about to resume
end

function <strong>sysCall_beforeInstanceSwitch</strong>()
    -- About to switch to another scene
end

function <strong>sysCall_afterInstanceSwitch</strong>()
    -- Switched to another scene
end

function <strong>sysCall_beforeCopy</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..key.." will be copied")
    end
end

function <strong>sysCall_afterCopy</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..key.." was copied")
    end
end

function <strong>sysCall_beforeDelete</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..key.." will be deleted")
    end
    -- inData.allObjects indicates if all objects in the scene will be deleted
end

function <strong>sysCall_afterDelete</strong>(inData)
    for key,value in pairs(inData.objectHandles) do
        print("Object with handle "..key.." was deleted")
    end
    -- inData.allObjects indicates if all objects in the scene were deleted
end

function <strong>sysCall_afterCreate</strong>(inData)
    for i=1,#inData.objectHandles,1 do
        print("Object with handle "..inData.objectHandles[i].." was created")
    end
end</pre>


<p>Add-ons can call any of the <a href="apiOverview.htm">regular API functions</a>, as long as not stated otherwise in the documentation. They can even call custom Lua functions registered by <a href="plugins.htm">plugins</a>. They however have two restrictions:</p>
<li>Add-ons cannot call API functions that require the caller to run in
a thread. This is because add-ons operate in a non-threaded fashion.</li>

<p>For more information on add-ons, make sure to inspect the content of the demo add-ons <em>simAddOnScript-addOnScriptDemo.lua</em>, <em>simAddOnFunc-addOnFunctionDemo.lua</em> and <em>simAddOnScript-b0RemoteApiServer.lua</em>, located in the installation folder.</p>
<br>
<br>
<h3 class="recommendedTopics">Recommended topics</h3>
<li><a href="http://www.lua.org">Lua</a></li>
<li><a href="plugins.htm">Plugins</a></li>
<li><a href="sandboxScript.htm">The sandbox script</a></li>
<li><a href="apiFunctionListAlphabetical.htm">Regular API functions</a></li>
<br>
<br>
 </td></tr>
</tbody></table> 
</div>  
  
  
</body></html>